CWSerenade Application Configuration | Contents | SCVs | Search | Glossary | Reports | Database | Solutions | XML | Index | JMS (Java Message Service) Providers for CWSerenade |
Configuring CWSerenade for SSL
SSL (Secure Socket Layer) is a communication protocol to manage the security of message transmission between CWSerenade and an external system, allowing you to encrypt the data passed between the client browser and the server.
Use the following steps to configure CWSerenade to use SSL communication.
Important: You must perform these steps on each of your CWSerenade application servers.
• Verify Java Version and Update PATH Variable
• Create a keystore and private Key
• Create a Certificate Signing Request File or Sign the Security Certificate Using an External Resource
• Export the Security Certificate To Make It Available to Install on Clients
• Import the Security Certificate into the Java Repository
• Configure Tomee to Allow SSL Communications
• Logging in to the SSL Enabled CWSerenade Application
Expired certificates: See Expired Security Certificate for instructions on removing a security certificate once it has expired.
Under the root drive where CWSerenade is installed, create a folder and name it SerenadeSSL.
Verify Java Version and Update PATH Variable
Verify that your current Java version is the same version used to run CWSerenade and add it to the PATH variable.
1. |
Advance to the following directory, where C: is the root directory where CWSerenade is installed: C:\Serenade\server\java |
2. |
The name of the folder located in the Java directory defines the version of Java you are using for CWSerenade. Example: jre7 If more than one folder exists, take note of the name of the folder with the highest name. For example, If the directory contains jre7 and jre8, take note of jre8. |
3. |
Add the following to the beginning of the PATH variable, where jre7 is the version of Java you noted in the previous step. C:\Serenade\server\java\jre7\bin To modify the PATH variable, advance to Start > Control Panel > System and Security > System and select Advanced System Settings. On the System Properties window, click Environment Variables. |
|
On the Environment Variables window, located the PATH variable and select Edit to modify its value. |
4. |
Verify the class path for the Java security programs. To verify: • Select Start > Run. At the Run window, type cmd and select OK to advance to a command prompt window. • At the command prompt window, type keytool and press Enter. The system displays a usage list: Note: If you received an error instead of a usage list, make sure you updated the PATH variable as described in the previous step. |
Create a keystore and private Key
1. |
Select Start > Run. At the Run window, type cmd and select OK to advance to a command prompt window. |
2. |
At the command prompt window, type the following, where servername.domain.com is the fully qualified name of the server and 365 is the number of days the keystore is valid. keytool -genkey -alias servername.domain.com -keyalg RSA -keystore c:\SerenadeSSL\tomcatkeystore -validity 365 Press Enter. |
3. |
The system displays the following questions. Answer each question as indicated below. • Keystore password: Enter serenade. • What is your first and last name: Enter the fully qualified server name. • What is the name of your organizational unit: Enter the name of your company. • What is the name of your organization: Enter the name of your company. • What is the name of your city or locality: Enter your city. • What is the name of your state or province: Enter your state or province. • What is the two-letter country code for this unit: Enter the two character country code (for example: US for United States, CN for Canada). The system displays what you entered and asks if it is correct. Enter yes. Enter key password for servername.domain.com: Press Enter to accept the default. |
4. |
To verify the keystore was created, advance to the following directory, where C: is the root drive where CWSerenade is installed. C:\SerenadeSSL In the SerenadeSSL folder, you should see a file named tomcatkeystore. • To self-sign the security certificate, see Create a Certificate Signing Request File. • To use an external resource, such as Verisign or InstantSSL, to sign the security certificate, see Sign the Security Certificate Using an External Resource. |
Create a Certificate Signing Request File
Use these steps if you wish to self-sign the security certificate; otherwise, see Sign the Security Certificate Using an External Resource.
Select Start > Run. At the Run window, type cmd and select OK to advance to a command prompt window.
At the command prompt window, type the following, where servername.domain.com is the fully qualified name of the server:
keytool -certreq -keyalg RSA -alias servername.domain.com -file c:\SerenadeSSL\certreq.csr -keystore c:\SerenadeSSL\tomcatkeystore
Press Enter. When the system prompts you for the keystore password, type serenade.
Sign the Security Certificate Using an External Resource
You can use an external resource, such as Verisign or InstantSSL, to sign the security certificate. Follow the instructions provided by the resource to sign the certificate. To self-sign the security certificate, see Create a Certificate Signing Request File.
Make sure the signed certificate reply is named serenadecert.cer.
When you receive the signed certificate reply, put it in the following directory, where C: is the root drive where CWSerenade is installed:
C:\SerenadeSSL
To install the certificate:
Select Start > Run. At the Run window, type cmd and select OK to advance to a command prompt window.
At the command prompt window, type the following, where servername.domain.com is the fully qualified name of the server:
keytool -import -alias servername.domain.com -keystore c:\SerenadeSSL\tomcatkeystore -trustcacerts -file c:\SerenadeSSL\serenadecert.cer
Press Enter.
When the system prompts you for the keystore password, type serenade.
Export the Security Certificate To Make It Available to Install on Clients
Select Start > Run. At the Run window, type cmd and select OK to advance to a command prompt window.
At the command prompt window, type the following, where servername.domain.com is the fully qualified name of the server:
keytool -export -keystore c:\SerenadeSSL\tomcatkeystore -file c:\SerenadeSSL\serenadecert.cer -alias servername.domain.com
Press Enter. When the system prompts you for the keystore password, type serenade.
To verify that the certificate was exported, advance to the following directory, where C: is the root drive where CWSerenade is installed.
C:\SerenadeSSL
In the SerenadeSSL folder, you should see a file named serenadecert.cer.
Import the Security Certificate into the Java Repository
You need to import the security certificate into the Java repository in order to enable the system to access web services via SSL.
Select Start > Run. At the Run window, type cmd and select OK to advance to a command prompt window.
At the command prompt window, type the following, where servername.domain.com is the fully qualified name of the server:
keytool -import -keystore C:\ Serenade\server\java\jre7\lib\security\cacerts -file C:\SerenadeSSL\serenadecert.cer -alias servername.domain.com
Press Enter.
When the system prompts you for the keystore password, type changeit and press Enter.
When the system asks whether to trust the certificate, type yes and press Enter.
The system displays a message indicating the certificate was added to the keystore.
Configure Tomee to Allow SSL Communications
1. |
Stop the SERENADE service if it is active; see Restarting CWSerenade. |
2. |
Advance to the following directory, where C: is the root drive where CWSerenade is installed: C:\Serenade\server\conf\server.xml |
3. |
In the jboss-web.sar folder, locate the file server.xml. |
4. |
Make a backup copy of the server.xml file in case you need to restore it. |
5. |
Open the server.xml file in a text editor and locate the following section: <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" keystoreFile="YOURKEYSTORE" clientAuth="false" keystorePass="YOURPASSWORD" sslEnabledProtocols = "TLSv1,TLSv1.1,TLSv1.2" />
|
6. |
Make the following changes: • Uncomment the block beginning with Connector port="8443" • Update the following attributes: • keystoreFile="C:\serenade\ssl\serenadekeystore • keystorePass="serenade" |
7. |
The updated section should look like the following: <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" keystoreFile="C:\serenade\ssl\serenadekeystore" clientAuth="false" keystorePass="serenade" sslEnabledProtocols = "TLSv1,TLSv1.1,TLSv1.2" />
|
8. |
Save and close the server.xml file. |
9. |
Advance to the following directory, where C: is the root drive where CWSerenade is installed: C:\Serenade\server\conf\cwdirectcpproperties\cwdirectcp.properties |
10. |
Make a backup copy of the cwdirectcp.properties file in case you need to restore it. |
11. |
Verify that the GWT_RESOURCE_URI property is set to the following: https://localhost:8443/SerenadeSeam/srs
Note: This property may not exist; if that is the case, you will need to add it. When SSL communication is turned off, this property setting looks like the following: https://localhost:8080/SerenadeSeam/srs |
12. |
Restart the SERENADE service. |
Logging in to the SSL Enabled CWSerenade Application
Use the following URLs to log in to the SSL enabled CWSerenade application:
To access CWSerenade in a browser window with address bar: |
https:\\servername.domain.com:8443\jenasys where servername is the name of the CWSerenade application server |
To access CWSerenade in a separate browser window: |
https:\\servername.domain.com:8443\CWSerenade.html where servername is the name of the CWSerenade application server |
Security certificate error: You will receive a web site security certificate error when you try to log in to CWSerenade if the browser does not trust the certificate. This may occur if you used a self-signed certificate, as described under Create a Certificate Signing Request File.
Example security certificate error screen:
Use the following steps to tell the browser to trust the certificate.
1. |
Click on Continue to this website (not recommended) to display the CWSerenade sign on screen. Notice that the URL displays in red and Certificate Error displays. ![]() |
2. |
Click on Certificate Error to display the following window: ![]() |
3. |
Click View certificates to advance to the Certificate window. At this window, click Install Certificate. ![]() |
4. |
The system starts the Certificate Import Wizard. At the Welcome window, select Next. |
5. |
At the Certificate Store window, select Place all certificates in the following store, click Browse, and select Trusted Root Certification Authorities. ![]() |
6. |
Select Next until you reach the Completion window. At this window, select Finish. ![]() |
7. |
If a Security Warning window displays, select Yes. |
8. |
When a success notification displays, select OK. ![]() |
9. |
Close and reopen the browser and enter the URL to log in to CWSerenade. You should no longer receive a security certificate error. |
When a security certificate expires, use the following steps to remove the expired certificate.
1. |
Select Start > Run. At the Run window, type cmd and select OK to advance to a command prompt window. At the command prompt window, type the following, where servername.domain.com is the fully qualified name of the server: keytool -delete -alias servername.domain.com -keystore c:\SerenadeSSL\tomcatkeystore Press Enter. |
2. |
Type the following, where jdk1.x.x_xx is the version of Java you are using: keytool -delete -alias servername.domain.com -keystore c:\ Serenade\server\java\jre\lib\security\cacerts Press Enter. |
3. |
Follow the previous instructions to apply a new certificate. See: • Verify Java Version and Update PATH Variable • Create a keystore and private Key • Create a Certificate Signing Request File or Sign the Security Certificate Using an External Resource • Export the Security Certificate To Make It Available to Install on Clients |